{% extends "api.html" %}
{% block api_content %}
<p>Chicago Boss liked <a href="http://docs.djangoproject.com/en/dev/topics/templates/">Django's templating language</a> so much, he decided to steal it. Template files go in your project's src/view/ folder (in subdirectories that correspond to the controller name), and will have access to the variables you pass from your <a href="api-controller.html#nav">Controller</a>. The template file associated with the function <code>foo_controller:bar</code> will be src/view/foo/bar.html. (Template filenames can also use <code>.txt</code>, <code>.dtl</code> and <code>.js</code> file extensions.)</p>

<p>Note: if you use the the <code>extends</code> tag, the file path should be relative to your project's src/view/ directory.</p>

<p>Chicago Boss has support for the most common features of the Django Template Language, so many existing Django templates should work out of the box. Your templates will be compiled down to Erlang BEAM code using <a href="http://code.google.com/p/erlydtl/">ErlyDTL</a> to give you the fastest Erlang templates this side of Stockholm.</p>

<p>100% of Django filters are supported. The only unsupported tag is csrf_token.</p>

<h2>Custom tags</h2>
<p>If you use repeated logic or template snippets, you can put helper templates into your project's src/view/lib/tag_html directory. The variables appearing in helper templates must be supplied by the caller. For example, if you have a file called "src/view/lib/tag_html/my_custom_tag.html" which uses a variable called "foo", you can invoke it from other templates like:</p>
<div class="code">
    {{ "{% " }}my_custom_tag foo="bar"{{ " %}" }}
</div>
<p>String literals or variables may be passed as arguments to custom tags.</p>
<p>Another option for factoring out repeated logic is to use ErlyDTL's "include" tag. The difference between using an "include" tag and custom tags is that "include" will have access to all variables currently in the caller's scope, whereas custom tags only have access to the variables explicitly passed in. (In addition, custom tags are compiled only once for the entire project, but included files are compiled for each template that includes it.)</p>
<h2>Helper modules for custom tags and filters</h2>
<p>For more complicated processing, you can create helper modules. Tag helper modules reside in src/view/lib/tag_modules, and export functions which take in a proplist of variables and return rendered HTML. Filter helper modules reside in src/view/lib/filter_modules, and export functions which take in a binary string and return a filter iolist. See those directories in your project for examples.</p>

<h2>Configuring ErlyDTL</h2>
<p>By default, ErlyDTL escapes HTML in values that are passed in template variables. This behaviour is configurable in CB, by setting the value of <code>template_auto_escape</code> to either <code>true</code> or <code>false</code> in <code>boss.config</code>.</p>

<h2>Implicit variables</h2>
<p>The following variables are automatically passed to your views without you doing any work:</p>
<ul>
    <li><code>_base_url</code> - The value of the config setting "base_url" or blank if not set</li>
    <li><code>_before</code> - The result of the authorization filter, if present</li>
    <li><code>_lang</code> - The content language of the rendered view</li>
    <li><code>_session</code> - Key/value pairs from the current session, if it exists</li>
</ul>

<h2>Experimental Template Languages</h2>
<p>Two other template languages are supported on an experimental basis: <a href="http://jade-lang.com/">Jade</a> (provided by <a href="https://github.com/graeme-defty/jaderl">jaderl</a>) and embedded <a href="https://github.com/elixir-lang/elixir">Elixir</a>.</p>
<h3>Jade</h3>
<p>To use Jade, simply create templates with extension ".jade".</p>
<h3>Embedded Elixir</h3>
<p>To use embedded Elixir, create templates with extension ".eex", and prefix your variables with <code>@</code>.</p>
<p>Example Elixir:</p>
<div class="code">
    A message for you: &lt;%= @message %&gt;<br />
    <br />
    &lt;%# This is a comment %&gt;<br />
    <br />
    &lt;%= Enum.map @puppies, fn(puppy) -&gt; %&gt;<br />
    Name: &lt;%= puppy.name %&gt;<br />
    &lt;% end %&gt;
</div>
<p>For more information on embedded Elixir, see <a href="http://elixir-lang.org/docs/master/EEx.html">the EEx docs</a>.</p>
{% endblock %}
